OctaMED Sound Studio 1/OctaMED SoundStudio V1.iso/utilities/midit.doc

Text File | 1996-06-18 | 22KB | 547 lines

****************************************************************
*                                                              *
*               MID-It! - MMDx to MID converter                *
*                                                              *
*               By Mario Bianchi - Version 1.7                 *
*                      Date: 26 May 1996                       *
*                                                              *
****************************************************************


    INTRODUCTION
    ------------

MID-It! is an OctaMED to MID music module file converter.

It was created due to personal needs: I use OctaMED for making
music at home, and sometimes I have to go to a music studio for
giving my work a more professional touch.

Well, in short I was very tired of carrying my Amiga environment
to the recording studios simply because the studio too had a
computer (always Atari or Mac, sigh!!!), but it was never able
to import OctaMED modules.

So I spent my spare time writing MID-It!.
It allows you to load an OctaMED music module (MMD0 or MMD1) and
get it converted in a few seconds to the universal MIDI file
format 1!

I won't stay here naming all the software products that can deal
with MIDI file format, just believe me when I say that they are
really many, on any computer platform (never heard of Cubase,
Notator, KCS Doctor T, and so on)?

I also know that this latest release is fully capable of
loading and saving MIDI 0 files too, but a lot of users prefer
saving as SMF 1 and because of time schedules, the author did
not have time to include SMF 1 format saving, you will find that
MID-It! happily saves format 1, though as yet it does not support
the new MMD2/3 modules.

I will only add these features if enough users ask me to,
( see contact address below ), otherwise I may just continue
development for my own needs in future.


    RESTRICTIONS AND REQUIREMENTS
    -----------------------------

The current version has some limitations:

 - Modules must be MMD0 or MMD1 type; these two module formats
   can be produced by all versions of OctaMED, and it seems to
   me that MED newer versions, too, have the ability to save
   using the MMD0 format.
   If you use OctaMED 5+, you can save your module using MMD0
   or MMD1 format, but be careful that your module does not
   use any of the extra features offered by MMD2 format
   (refer to OctaMED documentation), otherwise your music could
   loose some information if you save it using MMD0-1.

 - Modules should not contain any Amiga instruments (only MIDI
   stuff is allowed!)

 - Modules should contain supplementary info - instrument names
   and similar things, so be sure to save them using the right
   save settings from MED/OctaMED before submitting your music
   to MID-It!.

 - Only one song in a multimodule can be converted, (selectable
   using the brand new -m option).

 - Track volumes (ie the ones in the "volume" window of newer
   OctaMED releases) are currently not supported.

MID-It! works with any kickstart version from 1.1 to 3.1
- though I couldn't test it with all of them -
but needs medplayer.library 2+ in your LIBS: drawer.

If you plan to convert MMD1 modules, version 3+ is needed.

Version 5 and above should be found on the Octamed developer's
disk located on Aminet (file octamedv4_dev.lha in directory
"mus/edit", where you will also find a PD version of OctaMED.

Before using the library, though, read carefully the license
and distribution files included!


    USAGE
    -----

MID-It! is only a CLI command, but it can be better handled by a
good file manager like Directory Opus and Disk Master.

Using via this CD you simply open the cli in the system drawer
and issue your commands as below..

I'll add a small user interface if the program users - well
enough of them :-) - ask me to.

Usage: midit <options> <input file> <output file>

If <output file> is not specified, it will be <input file>,
modified as follows:

    - any leading "mod." or "med." is cut
    - any trailing ".mod" or ".med" is cut
    - extension ".MID" is appended to the filename

You can also specify only a path destination without filename,
Valid examples:

    midit -b -r ram:module
    midit -b -r -e -q ram:module ram:convmodule
    midit -breq ram:module ram:convmodule    (same as previous)
    midit -r ram:med.#? RAM:sound/

Please note the slash at the end of the last example: it must
ALWAYS be present if you specify a destination subdirectory
without destination filename, otherwise no output file will be
produced.

AmigaDOS wildcards "#?" can be used in the input filename to
convert several modules with a single command line, and a
special option is present to activate Unix and MS-DOS "*?"
wildcards, though excluding the AmigaDOS ones.

The output file is all in all a MIDI file format 1, but its
contents can be different, according to conversion type and
option selected.


    CONVERSION OPTIONS
    ------------------

Three types of conversion can be performed, depending on the
options specified.

Whatever conversion is used, the first track of the output MIDI
file has the name of the song and contains only tempo changes,
system exclusive messages, and various text events, if any.

The default conversion is the SMART one:
it creates a file with one track for each instrument used in
OctaMED plus the song track above mentioned.
If you don't specify any conversion option, this is the one that
will be performed.

The second conversion type is DIRECT (option -d):
it builds a track for each OctaMED block track (this version
supports up to 32 tracks per block, but in future this number
is very likely to grow up to 64).
Actually, the real MMD1 format was born for supporting up to
16 tracks per block, but newer releases of OctaMED allow the use
of MMD1 for songs containing blocks having ANY number of tracks
from 1 to 64.
Be aware though that most module players around could work right
only with older MMD1 modules, that can have only 4-8-12-16 tracks
per block, though MID-It does not suffer from this limitation.
The direct conversion generates a file in which the event
ordering is exactly the same (note by note, command by command)
as in OctaMED.

The third and last conversion is the CHANNEL one (option -c);
it features one track for each MIDI channel; that is, if you use
in a module more OctaMED instruments that share the same MIDI
channel, their events will be inserted in the same MIDI file
track.

Smart conversion is better (I think is is more clever to have
each instrument data in a separate track) but notes will be
played in a different order than on OctaMED - the real playing
order depends from the player routine.

This, especially when you are working near the maximum
poliphonic power of your MIDI machines, can make substantial
differences when listening to the output MIDI file.

Of course, should this happen, you can change the arrangement of
tracks to change note playing order.
You should do it easily using a MIDI sequencer (my hint is: put
first the rhythm instrument tracks).


    MISC OPTIONS
    ------------

Option -n can be used if you want that the MID file produced
uses MIDI Note Off messages to turn off a note (OctaMED and
Mid-It! default use instead Note On messages with 0 velocity).

Note Off messages have a fixed velocity of 127 (maximum value).
If you use this option together with running status (see below)
the file obtained will be longer than the 'only Note On' running
status one.
If you don't specify running status, file length is the same in
either Note On or Off formats.

Option -p suppresses the conversion progress indicator.

Option -r produces a .MID file containing running status data,
which is a simple method for compressing MIDI data.  A file
using this feature is, in general, much shorter than the
uncompressed one, but some sequencers (especially the very old
ones) could get confused; just try it on your configuration.

Option -t causes the converter to shut all notes when the module
ends (this way it can be played in loop without notes hanging
across).

Option -b is valid for MMD1 modules only: this switch activates
block name retain: block (or pattern, as you call them) name is
introduced as a text event in the MID file just at the moment it
starts to be played.

Option -e introduces an empty four beat bar before the real
module data begin. This is useful if you want to insert your own
MIDI setup messages before sound actually starts.

Option -u enables Unix/MS-DOS wildcards (*?) instead of the
AmigaDOS ones.  This is for who is used to such systems or for
converting a module which name contains the character # (the
symbol ? is a wildcard in Unix too).

Option -q enables quiet mode, suppressing any warning that
can be produced.
BE CAREFUL: if you suppress warnings you make it at your own
risk, because the conversion could be faulty and you could not
be aware of it; you'd better be sure that your module is 'solid'
before using this switch.

Option -m is useful when dealing with multisong modules (also
called multimodules): if the song you want to convert is *not*
the first in such a module, you can convert it using command -m,
followed by the number of the song in the module (1 to n).
By now only one song per module can be converted.

Option -s can be used to change the playing speed of your song:
when activated the file resulting from the conversion contains
tempo events which values are different from the original ones:
the time factor specified after the -s option is added to the
actual bpm value of each song tempo event.
For example -s2 causes the resulting midi song to be 2 beats per
minute faster than the input song (-s-2 would produce a slower
song).
Each and every tempo change event is altered, and resulting
values are clipped in the range 1-240 beats per minute.

Please note that when using one option that needs a numeric
argument, this one must follow close (with no spaces) to the
option letter and, if there are other options to be specified,
they have to be separately supplied.
I mean:

    options to convert a module using direct conversion
    and running status:

    -s3dr       Wrong: options 'd' and 'r' are ignored.
    -s 3 -dr    Wrong: the 3 should immediately follow the s.

    -s3 -dr     Correct
    -drs3       Correct

I hope this example was clear enough...


    WATCH OUTs, WARNINGS AND HINTS
    ------------------------------

If you use Amiga samples in your modules (together with MIDI or
alone) the modules won't be converted - in current version at
least.

There is a little workaround though: if you assign from OctaMED
a MIDI channel to every non MIDI instrument (thus promoting it
to MIDI), the module will be converted.
Simply, don't expect a perfect conversion: notes will have to be
transposed some octaves above and effects like pitchbend will
sound awful if you try to play the module through a MIDI device.
There is too much difference between Amiga and common MIDI sound
hardware to map in a simple way sound handling from one to the
other.  At least, with little work, you can get a MIDI file
containing all note events of your non MIDI instruments too.
This until a version fully supporting Amiga samples comes up, I
don't know when and even if it will (read DEVELOPEMENT NOTES
below).

For BPM modules, one thing is worth of being explained.
The slider at the right of the BPM one - I'm gonna call it
"Resolution" from now on - is intended as a 'slots per beat'
indication.
That is, if you set resolution to 8, then 8 block lines are
intended to form a metronome beat.  Keep it in mind if your
converted file sounds at different speeds than the original,
or if your sequencer metronome is not synchronized with song.
By now, I still haven't found a way to understand the signature
of an OctaMED song (how to find that a song has a 12/8 tempo??).
Because of this every MIDI file generated contains a 4/4
signature setting.

WARNING: if you use in your modules things such as pattern break
or song position jump to leap back in the song, the converter
will loop converting it forever!!!
It is recommended that you prevent this nasty accident preparing
your songs to be converted so that there is always an end.

ENFORCER HITS: if you have Enforcer active when converting
you could notice some occasional hits.
Deep investigations, together with OctaMED's author, Teijo
Kinnunen, have found that medplayer.library prior to
version 6 suffer from some bugs that can cause these hits,
sometime even bringing to an incorrect conversion.
The V6 library fixes these bugs successfully.
You can check the source of the hits using segtracker
together with Enforcer: if the hitting PC location is
reported in a medplayer.library hunk, this is one of the
above mentioned situations. Otherwise please report them
to me with as much detail as you can.
I just can't do anything about it but advise you to get
medplayer.library v6, as soon as the new OctaMED developer
disk is out on the streets - and it should be when you read this.

HINT: OctaMED 5+ has an hidden (undocumented on V5) command,
17xx, that writes directly byte xx into controller 7 (mostly
used for MIDI volume control).  I don't know if older versions
support it too, so, if you think that it could be useful for
you, just try it!!!


    DEVELOPEMENT NOTES
    ------------------

I have been putting all efforts to make the program bug free, but
there are many features involved and particular conditions that can
elude the bravest beta tester.  So you too can participate to make
the project more and more solid and functional (and you are invited
to do so). If you have questions or note a strange behaviour or
conversion mistakes, please contact me.

All the OctaMED commands and features that can be fit in a MIDI
module are implemented, but of course not all situations could be
actually tested (I am just a man and beta testers are too...).

You will find below (in program history) the list of last things
added, so be aware that these features are the less tested.

In previous versions of this product I told that the program was
under continuous developement, but now things have changed a bit.
Because of the low feedback level received so far, I really
wonder if this program is of any real use to anyone.
So, my current will is going on developing MID-It just to face
my needs; since the current version fullfills them almost
completely this could even mean that there could never be a
newer release.
I would have liked to add MMD2 support but, as far as I know,
this format has never really become of real use, maybe because
the OctaMED releases supporting it are commercial only.


    DISTRIBUTION
    ------------

This release of MID-It! is freely distributable, but only in the
form of the full original archive (midit.lha).
It is fully copyrighted by the author (Mario Bianchi) and you
are not allowed to use it inside a commercial product nor sell
it for profict without the written permission of the author.
You can upload and spread the original archive wherever you
wish, specifying that you are not the author.

I just ask for two more little things (don't flame me :->):

    1) If you use it frequently simply send me a postcard
       from where you live, I'd really appreciate it!
       This is not because I collect post cards, but instead
       because I would like to know how many people are using
       MID-It!, and what they think about it.

    2) I like feedback.
       Please report me of every trouble, information, opinion
       or enhancement you'd like to see or say about this
       program.
       I would also be glad if you could send me a short
       description of your Amiga musical activities and
       your usage - if any - of MID-It!


    FUTURE PLANS (no promises, but who knows...)
    --------------------------------------------

As you can see, there is still work to be done, and I am ready
to do what I can to get it useful for as many people as I can.
If people ask for a feature they'd like to find in a new
release, then it is more likely that I implement it if I know
that more people need it.

Just a few points that are floating in my mind:

    - As soon as I have some spare time, and I feel it could be
      really useful, a MUI version could be released...

    - Please don't ask to add complete Amiga samples support -
      or ask it all together, so that I can't say no.

      Sure, it would be a great result, but I think I can't get
      it all by myself in a short time (and I think it's better
      that people reach the Amiga-MIDI world, as soon as
      possible).
      If Amiga Tracker Guys can get so much from 4 poor 8 bit
      audio channels, God only knows what we can hear from them
      when they cross the bridge to real sound!!!
      Besides that, consider that most internal audio commands,
      like pitchbend, are really difficult to convert to MIDI,
      because they depend on many factors outside the module
      itself (MIDI device used, voice settings and so on).

    - One of the very next steps is let MID-It! support MMD2
      module format too.

    - Powerpacker, XPK and lha support (like OctaMED I hope).

I hope the development of this converter will closely follow
OctaMED's enhancements - or maybe OctaMED itself will be
enhanced in such a way to make MID-It! useless - who knows...
But this is up to you too: the success and diffusion of a
product depends very much upon people supporting it.


    DISCLAIMER
    ----------

This software and information is provided "as is".
No representations or warranties are made with respect to the
accuracy, reliability, performance, currentness, or operation
of this software and information, and all use is at your own
risk. The author does not assume any responsibility or liability
whatsoever with respect to your use of this software and
information.


    THANX TO...
    -----------

    - Scott Watson, Michael Whitten and JF Giorgi for being
      real friends and professional beta testers

    - Airon for kind support and Amiga music creation

    - Commodore for making Amiga

    - Teijo Kinnunen for writing OctaMED

    - The man who invented music (was he really a man?)


    REACHING THE AUTHOR
    -------------------

    You can contact me via email or normal mail.
    Addresses are

    Mario Bianchi                 email (!!! NEW address !!!)
    Via Bergamini 17
    20122 Milano ITALY            [e-mail]

    Email address is at University, so I can't guarantee ready
    (daily) answering.

    Bye and *** SHARE AND ENJOY AMIGA AND MUSIC ***


    PROGRAM HISTORY:

     4 March 1995 - project starts

     4 April 1995 - beta version 1.0 is ready.
                    Only BPM, pure MIDI, no instrument data
                    modules.
                    I've already converted thirty modules,
                    only getting polyphony problems with my
                    MIDI keyboard.

     6 April 1995 - Real (mailed) beta testing begins.

    23 April 1995 - Version 1.0 does little, but does it
                    well. Beta testers ask for MMD0 and
                    ST + SPD timing compatibility.

    25 April 1995 - Version 1.1 is ready for second phase of
                    beta testing.

       Changes:

       - Corrected bug when inserting program change in smart
         mode - it was put in the track of the previous
         instrument instead of the right one.

       - Added MMD0 comversion
       - Added decimal volumes dealing
       - Added ST and SPD compatibility
       - Added Channel conversion type

    30 April 1995 - First release is ready (v1.1a)

    5 May 1995 - Awful bug discovered and hopefully fixed:
                 various commands from FF1 to FFF caused also
                 a tempo change! -> V1.1b

    7 May 1995 - Version 1.2b presents lots of new features:
                 - Wildcard and filename extensions handling
                 - Options -b, -e, -q, -u
                 - A few (minor) bugs fixes
                 - Annotation text saved as text event
                 - Total playing time computed and inserted
                   as text event
                 - Enhanced option parser - can specify
                   multiple options attached, like -qre
                 - Due to wildcard support, inserted scan and
                   conversion statistics

    23 May 1995 - No bug reports from beta testers -
                  ready for Aminet upload!

    13 Jul 1995 - V1.2c:
                  Discovered and fixed bug preventing many
                  MIDI effects from being correctly converted.
                  Lifted max tracks per block to 32 because
                  OctaMED 5+ can save MMD1 modules having
                  blocks made of more than 16 tracks.

    17 Sep 1995 - V1.2d (never released):
                  Slight correction: the warn track number for
                  message 'not a MIDI instrument' was wrong.

    19 Nov 1995 - v1.5:
                  Added time shift option and multimodule
                  support.

    18 Feb 1996 - v1.6:
                  Corrected bug that caused wrong timing information
                  when secondary tempo was not permanently set at 6.

    26 May 1996 - v1.7:
                  Corrected bug in retrig commands: the instrument and
                  song transpose were summed to the note value for each
                  retrig.